MACD 5

home *** CD-ROM | disk | FTP | other *** search

/ MACD 5 / MACD 5.bin / workbench / commodity / stroke / stroke.doc < prev

Wrap

Text File | 1996-12-01 | 14KB | 394 lines

Stroke Commodity 0.9 (1.12.96) Pasi 'Albert' Ojala albert@cs.tut.fi http://www.cs.tut.fi/~albert/ What is Stroke Commodity? ~~~~~~~~~~~~~~~~~~~~~~~~~ Stroke commodity is a mouse-controlled Intuition event generator. That's a short explanation. A longer version explains that you can draw different symbols using the mouse and the commodity will then interpret them and insert the appropriate events into the input stream. Strokes are most useful with a 3-button mouse. You assign the middle button to be the stroke 'key'. Press the button down, draw a symbol, and release the button. Stroke commodity will then check what you wanted, creates the corresponding input events and inserts them into the input event chain. Installation ~~~~~~~~~~~~ Use the accompanied installation script. It installs all files needed into a directory, and optionally installs a launcher icon into the WBStartup drawer. Default 4-color icons and MagicWB icons are available. Start the commodity by double-clicking either the startup-icon or the installed version. You can then press the default popkey combination control + left alt + s to open the commodity's window so that you can configure it to your liking. Theory of Operation ~~~~~~~~~~~~~~~~~~~ When you press the stroke button with the right qualifier key(s) pressed, the commodity starts to record mouse movements. When you release the button, a series of operations is performed on the recorded movements. These movements are relative, i.e. they represent the relative movement of the mouse. This movement is first filtered with a median filter to get rid of some noise. Then the movement is changed from relative to absolute coordinates. Minimum and maximum values in both directions (horizontal and vertical) are determined. These values represent the rectangular region which contain the stroke. The stroke is scaled into a 3-by-3 matrix. However, if the rectangle is more than two times as wide/high as high/wide, the original aspect ratio is preserved. This makes it possible to have single horizontal and vertical strokes. If the absolute movement in horizontal or vertical direction is very small, that movement is discarded. The stroke then has no movement. When the stroke has been scaled, it is converted back to relative coordinates for detection. Direction-length -representation is the logical format, even if it is a bit differently handled in the program. Anyway, detection is tried next. The new stroke is compared to existing strokes. Generally it is necessary that the strokes have the same lines (the same direction and length) in the same order. The first line and the last line in the stroke are exceptions, they only need to have the same direction. If a match is found, the corresponding action is performed (unless "watch only" is selected). If there is no match, and "learn mode" is activated, the new stroke is added and gets the currently selected action as a default action. This action can be later changed or the stroke can be deleted. The stroke is also shown in the commodity's window. If the window isn't open, it's opened and the screen is brought to front. If there was no match and "learn mode" was not activated, nothing happens. The Edit Window: ~~~~~~~~~~~~~~~~ Qualifier Selection: -------------------- Qualifier Button Here you can select the button and the qualifiers you need when making strokes. Middle button is the default. When you select qualifier keys and change the button, the change will only take place if you use "Apply", "Save", or "Use". This also applies to the "Relaxed" selection, but does not apply to the stroke and action editing and commands. Exact Match Selects exact/relaxed qualifiers. In either mode you need to press the selected qualifiers, in relaxed mode you can also press additional qualifiers. In exact match mode you can only press the selected qualifiers. Apply This gadget updates the current qualifiers, stroke button and "relaxed" setting. Is equal to "Use", except that it does not close the window. This is not really "Test", like in many other preference and commodity programs, because "Cancel" does not restore old settings. Stroke Controls: ---------------- Watch Only If this box is checked, strokes will not cause any input events to be generated. This is useful when you are initially teaching a lot of commands and don't want them to be 'executed'. Learn Mode When this box is checked, strokes that are not recognized are automatically added. The preferred sequence in teaching new commands is to first select/set the required action (input event description) and then draw the stroke. A new stroke is always associated with the action currently selected. A new action can be set using the "Bind" gadget. Stroke <> These two small gadgets are used to step through the existing strokes. The action display is updated to show the action associated with the current showing stroke. Delete This button deletes the current stroke. Action Controls: ---------------- Action <> These gadgets are used to select the right action for a stroke. Action String Write the action you want here. The action will be updated when you press return, so don't forget to press it. This changes the action for all strokes that has that action "bound" to them. Bind This gadget associates the current action with the current stroke. If the current stroke has already the current action, this gadget is ghosted. Qualifier/Window Controls: -------------------------- Save The selected stroke qualifiers and button will become active. Also saves preferences to the icon file, saves strokes if they have been changed and closes the window. Use The selected stroke qualifiers and button will become active. Also closes the window. Cancel Closes the window without changing the stroke qualifiers or the button. Menus: ~~~~~~ Project: -------- Save Strokes Saves current strokes and their actions whether they have been changed or not. Save Prefs Saves current preferences whether they have been changed or not. About Opens/closes an about-requester. This is an asynchronous window, so you can use strokes while the requester is open. Hide Closes the window but keeps the commodity resident. Quit Quits the commodity. If you try to quit when there are unsaved strokes/actions, you are asked if you want to save them. Edit ~~~~ Reset to Defaults Initializes the preferences to the default values. Last Saved Reads in the lastly-saved preferences and strokes/actions. Clear All Clears all actions and removes all strokes. Teaching Strokes ~~~~~~~~~~~~~~~~ Teaching new strokes and actions is best described using an example. You want to teach a stroke that changes screens. You have decided that an up-arrow would be the right stroke. 1) Start the commodity so that it opens its window. (If you have CX_POPUP=NO in the icon, run the program again and it will open its window, or use commodity exchange to ask the commodity to open its window.) You can also open the window by pressing the popkey, by default control-left alt-s (<ctrl lalt s>). 2) Check boxes "Learn Mode" and "Watch Only" 3) Select a free action, activate the string gadget and write "<lcommand m>", not including the quotes. (lcommand means the left amiga key, and left amiga+m is the screen shuffle combination.) 4) Remember to press return so that the action is really updated. 5) Press down the required qualifier keys and the stroke button (by default no qualifiers, just the middle button) 6) Move the mouse directly upwards, a moderate amount. 7) Release the button and/or qualifiers 8) The stroke you just made should appear. If it didn't, you used a wrong qualifier-button combination or didn't have the "Learn Mode" active. The first line in the stroke is drawn in different color than the rest so that it would be easier to see where the stroke starts. 9) If the stroke doesn't correspond to an up-arrow you draw, press "Delete", select the action that has "<lcommand m>" and try again. If it did, you can deselect "Learn Mode" and "Watch Only" and try out the action you just taught. Changing Actions ~~~~~~~~~~~~~~~~ Many strokes can have the same action. If you want to change an action you have to options: 1) Change the action itself - all strokes that had that action still has that action, it's just different now. Just write a new action text into the string gadget and press return. 2) Select a new action to a stroke - only the current stroke's action will be changed. In this case use the "Bind" gadget to set the new action to the stroke. Small List of Events ~~~~~~~~~~~~~~~~~~~~ smake\n - "smake" followed by a return <rcommand q> - right amiga + q, standard "quit" shortcut <ctrl lalt help> - control + left alt + help, default exchange hotkey <ctrl x> - control + x, shell delete-line command <f1> - the first function key <rawmouse mouse_leftpress><rawmouse upstroke mouse_leftpress> - simulates left mouse button press Features & Hints ~~~~~~~~~~~~~~~~ If you select (and "apply" or "use") left or right mouse button without any qualifiers, the commodity will not filter those button events. This is because it would become somewhat difficult to change the settings or use menus. However, if you select middle mouse button or either of the other buttons with at least one qualifier, button events with those qualifiers are filtered. Popkey events are also filtered, they are not seen by other commodities or applications. There were occasional small reversing-effects coming from the mouse. A median filter was added to remove small mouse glitches. Do not use complex strokes! The more complex you make your strokes, the more of them you need to teach to get all the possible combinations of mouse movements. With single straight lines you already have eight strokes, with two straight lines you have 32 more. These usually need only one stroke to be recognized correctly, something like O needs 2-4 different strokes. (O or 0 is a stroke that is actually quite usable.) On the other hand, using only two-line strokes will present a problem in remembering which stroke does what. Try to pick intuitive strokes. For example, I assigned amiga-Q to a "bottom-right to top-left" stroke. A logical extension to this was a stroke "bottom-right, top-left, bottom-left" bind to amiga-H. Simple up-stroke was intuitive for screen changing (left amiga M). Preferences are saved into tooltype entries in the icon file. If there is no icon file when you save preferences, a default tool icon is created and the settings are saved there. You can change the settings using e.g. workbench "info" command and then load them using "Last Saved" in the commodity's edit menu. The strokes and actions are saved into a separate file. By default the file is "PROGDIR:Stroke.data", which describes a file in the same directory as the executable. You can change the filename from the tooltype named "DATAFILE". "Last Saved" will try to read the datafile, "Save Strokes" writes it. An icon is currently created for the data file. This makes it easier to move the commodity AND the datafile from one place to another. For example you can just drag the commodity and the data file to WBStartup-drawer and be done with it. Oops, I take that back, seems it's not that simple. Because WB gets confused when you have an icon for the datafile in the WBStartup directory, I recommend that you install Stroke into its own directory and just copy a project icon with the default tool stroke (and whatever the path will be) into the WBStartup drawer. (The install script does this.) This has two advantages: 1) you don't need to copy the catalog files and 2) everything stroke-related will be kept in the same directory. So, if you later remove the stroke commodity, it'll be easier. You can't define an action that invokes strokes. You need to send stroke button press and stroke button release events, but because of how the commodity works, only the button press will be received by the commodity when generated by the commodity itself. Bugs & To do ~~~~~~~~~~~~ The old popkey remains active even if you select "Reset to Defaults" or "Last Saved". Live with it or quit and restart stroke commodity after changing the hotkey. The executable really needs to be named "Stroke". If you always start the commodity from shell, you can rename it to anything you like, but then you shouldn't start it from workbench anymore. Greetings go to: Henrik Herranen For talking about the idea so many times. Janne Salmijärvi For mental support.. Timo Kaikumaa For testing and suggestions Event generation ~~~~~~~~~~~~~~~~ Format: '<' [<type>] [[-]<qualifier>] [<direction>] <keydef> '>' or <ascii-text> Type: DISKINSERTED DISKREMOVED EVENT NEWPOINTERPOS NEWPREFS POINTERPOS RAWKEY RAWMOUSE TIMER Qualifier: CAPSLOCK CAPS_LOCK CONTROL CTRL LALT LAMIGA LBUTTON LCOMMAND LEFTBUTTON LEFT_ALT LEFT_AMIGA LEFT_BUTTON LEFT_COMMAND LEFT_SHIFT LSHIFT MBUTTON MIDBUTTON MIDDLEBUTTON MIDDLE_BUTTON NUMERICPAD NUMERIC_PAD NUMPAD NUM_PAD RALT RAMIGA RBUTTON RCOMMAND RELATIVEMOUSE REPEAT RIGHTBUTTON RIGHT_ALT RIGHT_AMIGA RIGHT_BUTTON RIGHT_COMMAND RIGHT_SHIFT RSHIFT ALT CAPS SHIFT Key direction: UPSTROKE Special keys: BACKSPACE BREAK COMMA CURSOR_DOWN CURSOR_LEFT CURSOR_RIGHT CURSOR_UP DEL DELETE DOWN END ENTER ESC ESCAPE F1 F10 F11 F12 F2 F3 F4 F5 F6 F7 F8 F9 HELP HOME INSERT LEFT PAGE_DOWN PAGE_UP PAUSE RETURN RIGHT SPACE SPACEBAR TAB UP Rawmouse button events: MOUSE_LEFTPRESS MOUSE_MIDDLEPRESS MOUSE_RIGHTPRESS Keypad keys: ( ) * + - . / 0 1 2 3 4 5 6 7 8 9 / .